src/main/java/io/mailtrap/model/response/stats/SendingStatGroupResponse.java (1)

13-18: Guard against silently overwriting extra dynamic fields.

Every non-stats property replaces name and value. If this payload ever gains another top-level field, the first group key is lost with no signal. Consider rejecting a second dynamic key or storing extras explicitly instead of overwriting them.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/main/java/io/mailtrap/model/response/stats/SendingStatGroupResponse.java`
around lines 13 - 18, The current JsonAnySetter in SendingStatGroupResponse
(setDynamicField) blindly overwrites name/value for every non-"stats" key,
losing the first key; change setDynamicField to preserve the first encountered
dynamic key by: add a new Map<String,Object> extras field on
SendingStatGroupResponse, set name and value only if name is null (or blank) on
first non-"stats" key, and for any subsequent non-"stats" keys put them into
extras instead of overwriting; alternatively (if you prefer strictness) throw an
IllegalArgumentException when a second dynamic key is encountered—implement one
of these behaviors and update setDynamicField to check existing name before
mutating it and to populate extras (or throw) accordingly.

src/test/java/io/mailtrap/api/stats/StatsImplTest.java (1)

30-40: Add coverage for the list-filter query params.

These fixtures only assert start_date/end_date, but src/main/java/io/mailtrap/api/stats/StatsImpl.java:72-80 also serializes sending_domain_ids[], sending_streams[], categories[], and email_service_providers[]. If one of those keys is misspelled or emitted incorrectly, this suite still stays green.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/test/java/io/mailtrap/api/stats/StatsImplTest.java` around lines 30 - 40,
The tests only assert start_date/end_date; update the test to include the
list-filter query params that StatsImpl.serializeFilters emits
(sending_domain_ids[], sending_streams[], categories[],
email_service_providers[]) so the suite will catch misspellings: add those keys
with representative values to the defaultQueryParams Map used by TestHttpClient
(the variable currently named defaultQueryParams) and ensure each DataMock.build
entry in the TestHttpClient expectations includes those same keys (matching the
bracketed parameter names) so requests created by StatsImpl (methods in
StatsImpl that serialize filters around lines 72-80) must include the list
params to satisfy the mocks.

src/main/java/io/mailtrap/api/stats/StatsImpl.java (1)

76-80: ⚠️ Potential issue | 🟡 Minor

Reject blank date values too.

Whitespace-only startDate / endDate still pass these checks and get sent as invalid query params. Trim or blank-check them here so callers fail fast.

Suggested fix

-        if (filter.getStartDate() == null || filter.getStartDate().isEmpty()) {
+        if (filter.getStartDate() == null || filter.getStartDate().trim().isEmpty()) {
             throw new IllegalArgumentException("startDate must not be null or empty");
         }
-        if (filter.getEndDate() == null || filter.getEndDate().isEmpty()) {
+        if (filter.getEndDate() == null || filter.getEndDate().trim().isEmpty()) {
             throw new IllegalArgumentException("endDate must not be null or empty");
         }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/main/java/io/mailtrap/api/stats/StatsImpl.java` around lines 76 - 80, The
current validation in StatsImpl (checks on filter.getStartDate() and
filter.getEndDate()) allows whitespace-only strings; update the validation to
reject blank values by trimming before emptiness check (e.g., if
(filter.getStartDate() == null || filter.getStartDate().trim().isEmpty()) and
similarly for getEndDate()) so callers fail fast and no whitespace-only dates
are sent as query params; keep throwing IllegalArgumentException with the same
messages.

examples/java/io/mailtrap/examples/general/StatsExample.java (1)

19-22: Use placeholder dates in the sample.

A fixed January 2026 window will go stale and can easily return empty results for readers. Placeholder values or named constants keep the example evergreen.

Suggested tweak

-        final var filter = StatsFilter.builder()
-                .startDate("2026-01-01")
-                .endDate("2026-01-31")
+        final var filter = StatsFilter.builder()
+                .startDate("<START_DATE: YYYY-MM-DD>")
+                .endDate("<END_DATE: YYYY-MM-DD>")
                 .build();

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/java/io/mailtrap/examples/general/StatsExample.java` around lines 19
- 22, The sample uses fixed dates in StatsFilter.builder() which will become
stale; replace the hard-coded "2026-01-01"/"2026-01-31" values in the
StatsExample's filter variable with placeholder constants or descriptive
variables (e.g., START_DATE/END_DATE or "YYYY-MM-DD" strings) and/or add a short
comment explaining they should be set by the user; update the
StatsFilter.builder().startDate(...) and .endDate(...) calls to use those
placeholders so the example remains evergreen.

src/test/java/io/mailtrap/api/stats/StatsImplTest.java (1)

31-41: Add coverage for list-filter query serialization.

These mocks only verify start_date and end_date. The new behavior in this PR is the optional list filters with [] query keys, but none of the tests exercise sending_domain_ids[], sending_streams[], categories[], or email_service_providers[]. Please add at least one positive-path case that asserts those parameters are serialized correctly, since that is the easiest part of this feature to break.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/test/java/io/mailtrap/api/stats/StatsImplTest.java` around lines 31 - 41,
The current TestHttpClient mocks only assert start_date/end_date; add a
positive-path mock that verifies the new list-filter query serialization (keys
with []), e.g. create an expectedQueryParams map including
"sending_domain_ids[]", "sending_streams[]", "categories[]", and
"email_service_providers[]" mapped to their expected list values alongside
start_date/end_date, and add a DataMock.build entry that uses that map (similar
to existing builds) so the StatsImplTest (TestHttpClient/DataMock.build) asserts
those array-style query keys are sent correctly.

examples/java/io/mailtrap/examples/general/StatsExample.java (1)

1-43: LGTM!

The example clearly demonstrates usage of all Stats API methods with proper fluent API chaining. The placeholder values and date format comment provide good guidance for users.

Consider adding an example using optional filter parameters (e.g., sendingDomainIds, sendingStreams) to showcase the full filtering capability:

final var filterWithOptions = StatsFilter.builder()
        .startDate(START_DATE)
        .endDate(END_DATE)
        .sendingDomainIds(List.of(1L, 2L))
        .sendingStreams(List.of(SendingStream.TRANSACTIONAL))
        .build();

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@examples/java/io/mailtrap/examples/general/StatsExample.java` around lines 1
- 43, Add a second example showing optional StatsFilter parameters: create a new
variable (e.g., filterWithOptions) using StatsFilter.builder() and set
startDate/endDate plus sendingDomainIds (List.of(...)) and sendingStreams (e.g.,
SendingStream.TRANSACTIONAL) to demonstrate advanced filtering; call the same
client.sendingApi().stats() methods (getStats, byDomain, byCategory,
byEmailServiceProvider, byDate) with ACCOUNT_ID and filterWithOptions and add
necessary imports (java.util.List and the SendingStream enum) at the top of
StatsExample.java.